3D Graphics Programming with QuickDraw 3D 1.5.4

Managing Strings

QuickDraw 3D provides routines that you can use to manage string objects (or strings).

Q3String_GetType

You can use the Q3String_GetType function to get the type of a string.



 
TQ3ObjectType Q3String_GetType (TQ3StringObject stringObj);

stringObj: A string object.

DESCRIPTION

The Q3String_GetType function returns, as its function result, the type of the string specified by the stringObj parameter. The type of string currently supported by QuickDraw 3D is defined by a constant:



 
kQ3StringTypeCString

If the type of the string cannot be determined or is invalid, Q3String_GetType returns the value kQ3ObjectTypeInvalid .

Q3CString_New

You can use the Q3CString_New function to create a new C string.



 
TQ3StringObject Q3CString_New (const char *string);

string: A pointer to a null-terminated C string.

DESCRIPTION

The Q3CString_New function returns, as its function result, a new string object of type kQ3StringTypeCString using the sequence of characters pointed to by the string parameter. That sequence of characters should be a standard C string (that is, an array of characters terminated by the null character). The characters are copied into the new string object's private data, so you can dispose of the array pointed to by the string parameter if Q3CString_New returns successfully. If Q3CString_New cannot allocate memory for the string, it returns the value NULL .

Q3CString_GetLength

You can use the Q3CString_GetLength function to get the length of a C string object.



 
TQ3Status Q3CString_GetLength (

                     TQ3StringObject stringObj, 

                     unsigned long *length);

stringObj: A C string object.
length: On exit, the length of the specified C string object.

DESCRIPTION

The Q3CString_GetLength function returns, in the length parameter, the number of characters in the data associated with the C string object specified by the stringObj parameter. The length returned does not include the null character that terminates a C string. You should use Q3CString_GetLength to get the length of only string objects of type kQ3StringTypeCString .

Q3CString_GetString

You can use the Q3CString_GetString function to get the character data of a C string object.



 
TQ3Status Q3CString_GetString (

                     TQ3StringObject stringObj, 

                     char **string);

stringObj: A C string object.
string: On entry, the value NULL . On exit, a pointer to a copy of the character data associated with the specified C string object.

DESCRIPTION

The Q3CString_GetString function returns, through the string parameter, a pointer to a copy of the character data associated with the C string object specified by the stringObj parameter. The value of the string parameter must be NULL when you call Q3CString_GetString , because it allocates memory and overwrites the string parameter. For instance, the following sequence of calls will cause a memory leak:



 
myStatus = Q3CString_GetString(myStringObj, &myString);

myStatus = Q3CString_GetString(myStringObj, &myString);

After the second call to Q3CString_GetString , the memory allocated by the first call to Q3CString_GetString is leaked; you cannot deallocate that memory because you've lost its address. You must make certain to call Q3CString_EmptyData to release the memory allocated by Q3CString_GetString when you are finished using the string data, and always before calling Q3CString_GetString with the same string pointer. Here is an example:



 
myStatus = Q3CString_GetString(myStringObj, &myString);

myStatus = Q3CString_EmptyData(&myString);

myStatus = Q3CString_GetString(myStringObj, &myString);

If the value of the string parameter is not NULL , Q3CString_GetString generates a warning.

You should use Q3CString_GetString only with string objects of type kQ3StringTypeCString .

ERRORS AND WARNINGS

kQ3WarningPossibleMemoryLeak

Q3CString_SetString

You can use the Q3CString_SetString function to set the character data of a C string object.



 
TQ3Status Q3CString_SetString (

                     TQ3StringObject stringObj, 

                     const char *string);

stringObj: A C string object.
string: On entry, a pointer a C string specifying the character data to be associated with the specified C string object.

DESCRIPTION

The Q3CString_SetString function sets the character data associated with the C string object specified by the stringObj parameter to the sequence of characters pointed to by the string parameter. That sequence of characters should be a standard C string (that is, an array of characters terminated by the null character). The characters are copied into the specified string object's private data, so you can dispose of the array pointed to by the string parameter if Q3CString_SetString returns successfully.

You should use Q3CString_SetString only with string objects of type kQ3StringTypeCString .

Q3CString_EmptyData

You can use the Q3CString_EmptyData function to dispose of the memory allocated by a previous call to Q3CString_GetString .



 
TQ3Status Q3CString_EmptyData (char **string);

string: On entry, a pointer to a copy of the character data returned by a previous call to Q3CString_GetString . On exit, the value NULL .

DESCRIPTION

The Q3CString_EmptyData function deallocates the memory pointed to by the string parameter. The value of the string parameter must have been returned by a previous call to the Q3CString_GetString function. If successful, Q3CString_EmptyData sets the value of the string parameter to NULL . Thus, you can alternate calls to Q3CString_GetString and Q3CString_EmptyData without explicitly setting the character pointer to NULL .

You should use Q3CString_EmptyData only with string objects of type kQ3StringTypeCString .